Using the formula builder to configure an advanced formula
- In the IEE application, go to Meter Data Management > Application Data > Interactive Graphing.
- Select a service point channel.
- Select the Formula tab.
-
Select the Advanced tab. The Expression Builder window appears.
- Click Build Formula.
This button appears in a window only if the Formula Builder is available.
or
Select Meter Data Management > Application Data > Named Formulas.
The Formula Builder dialog appears.
- Select the Advanced tab.
Enter the formula directly into the white board, or use the Expression Builder tool.
- Click Builder to open the Expression Builder dialog.
-
Within the Expression Builder, navigate through a categorized tree of UCE tokens. As you click each category (folder) or UCE token, the Expression Builder displays descriptions and examples that help simplify the formula building process.
Functions: see Functions for additional details on the functions available here.
Within the Functions folder are the sub-categories:
-
These functions convert from one or more units to a target unit and support power triangle conversions.
Table 1268 Functions Term
Definition
Ampsi2h
sqrt(IPH*args[0].value)
I2hi
SQ(args[0].value)/IPH
I2hih
SQ(args[0].value*IPH)/IPH
I4hi2h
IPH*SQ(args[0].value)
Ihi2h
sqrt(args[0].value*IPH/IPH
Kqhvarh
(args[1].value*SQRT3+args[0].value)/2
Kvah
SQRT_SUM_SQS(args[0].value,args[1].value)
Kvarh
SQRT_DIFF_SQS(args[1].value,args[0].value)
Kvarhq
(2*args[1].value)-args[0].value/sqrt(3)
Kwh
SQRT_DIFF_SQS(args[1].value,args[0].value)
Pf
args[0].value/SQRT_SUM_SQS(args[0].value,args[1].value))
Pfwva
divide(req,args[0].value,args[1].value)
V2hv
SQ(args[0].value)/IPH
V2hvh
SQ(args[0].value*IPH)/IPH
V4hv2h
IPH*SQ(args[0].value)
Vhv2h
sqrt(args[0].value*IPH)/IPH
Voltsv2h
sqrt(IPH*args[0].value)
-
All quantities returned by the date functions are represented as floating point values, so a time of noon returned by @time would be equal to a value of 120000.0. The @holiday function returns 1.0 if the local time of the current interval falls within a day defined to be a holiday, 0.0 otherwise. In all the functions, the argument is the current interval of the given channel.
Table 1269 Functions Term
Definition
Date
The date in YYYYMMDD format
Datetime
The datetime in YYYYMMDDHHMMSS format
Day
A number from 1-31 signifying day of the month
Daytype
Returns a number from 1-7 where Sunday=1
Holiday
Is the interval on a holiday or not. 1.0 for true or 0.0 for false. For more information about creating Holiday Lists, see .
Month
A number from 1-12 where January=1
Time
The time in HHMMSS format
Year
The year, for example 1999, 2009
Note: Holidays must be included in a Holiday List called Default for the holidays to apply when IEE generates baselines. Holidays included in other lists are not considered holidays with respect to baselines.
Table 1270 Functions Term
Definition
Date
The date in YYYYMMDD format
Datetime
The datetime in YYYYMMDDHHMMSS format
Day
A number from 1-31 signifying day of the month
Daytype
Returns a number from 1-7 where Sunday=1
Holiday
Is the interval on a holiday or not. 1.0 for true or 0.0 for false. For more information about creating Holiday Lists, see .
Month
A number from 1-12 where January=1
Time
The time in HHMMSS format
Year
The year, for example 1999, 2009
-
These functions return a single value and can be used anywhere inside a formula. Scalar IF (SIF) returns 1.0 for true and 0.0 for false.
Table 1271 Functions Term
Definition
Avg
The scalar average across the interval stream
Lf
Compute load factor, defined as total usage/(max demand*total time), in hrs
NLow
Returns the nth low
NPeak
Returns the nth peak
SAbs
Currently always returns 0
SIf
Returns 1 if expr is true, 0 otherwise.
Status Count
Returns the number of times given status appears in the interval stream
Sum
The scalar sum across the interval stream
Zero Count
Total number of zero intervals (tolerance of 0.00001)
-
These functions can take as an argument any expression that results in a channel stream of interval data. The functions for vector sum, average, min and max take a list of such expressions (which could just be channel references), optionally followed by a list of named exclude conditions.
Table 1272 Functions Term
Definition
Abs
The absolute value of the argument
Arccos
Arccosine returns a value in the range 0 to 180 degrees and assume argument is between -1 and 1, non-inclusive
Arcsin
Arcsine returns a value in the range of 0 to 180 degrees and assume argument is between -1 and 1, non-inclusive
Arctan
Arctan returns a value in the range of -90 to 90 degrees
Cos
Cosine of the argument. Argument assumed to be in degrees
IAvg
Takes two or more arguments and returns avg. Allows exclude conditions. For explicity defined channels
IAvg (Group)
Takes the service point channels included in a configuration group and returns avg. Allows exclude conditions.
If
Standard "if" operation
IMax
Takes two or more arguments and returns max. Allows exclude conditions
IMax (Group)
Takes the service point channels included in a configuration group and returns max. Allows exclude conditions.
IMin
Takes two or more arguments and returns min. Allows exclude conditions
IMin (Group)
Takes the service point channels included in a configuration group and returns min. Allows exclude conditions.
ISum
Takes two or more arguments and returns sum. Allows exclude conditions
ISum (Group)
Takes the service point channels included in a configuration group and returns sum. Allows exclude conditions.
Neg
The argument unless argument is >0, then 0
Pos
The argument unless argument is <0, then 0
Sin
Sine of the argument. Argument to be in degrees
Sqrt
Square root of the argument. Assumes argument >0
Square
The argument squared
Tan
Tangent of the argument. Argument assumed to be in degrees
-
Table 1273 Special Term
Definition
Demand
The demand will convert the interval data stream to demand values appropriate to the output unit of measure
Energy
Energy is a no-op solely for documentation purposes
Primary
Primary is a special function that converts the literal service point channel to 'primary' instead of secondary units
Profile Register Data
Computes interval data from a consumption register channel and a load shape channel.
Example: @profilereg(A:101,B:1), where A:101 is a consumption register channel and B:1 is an interval channel containing the loadshape to use.
This function can only be used in a stored formula channel, at the top level of a formula, and it must be aggregated for the exact time ranges of the register values. The first parameter must be any supported type of explicit reference to a register channel (service point ID ‘:’ channel number, $sp, $spc, etc.). The second parameter can be any expression which evaluates to an interval stream.
Pulse
Pulse only takes a few specific arguments: either a single, literal service point channel reference, or a @kqhvarh function whose kvarh argument is a single, literal service point channel reference. The formula used is Round((Value+Pulse offset)/(Pulse Multiplier))
Register Usage
Returns the consumption, in KWH, for a consumption register channel. Example: @regusage(A:1), where A:1 is a consumption register channel.
They must be aggregated for the exact time ranges of the register values. There must be a read on the register channel at the start and end of the aggregation or at the start and end of another requested time span. Critical changes (such as meter swaps) are supported as long as there is an end read at the exact time of the change and a start read also at the same time. Only physical register channels can be the source for this function. If the source is not a physical register channel, no readings are returned and an error displays.
Secondary
Secondary is a special function that converts the literal service point channel to 'secondary' instead of primary units.
TransformerLosses
Calculates transformer losses using the same T model used in MV-90. Example: @tlosses(A:1,0.0002,0.0141,W,A:5,NA) calculates the losses against A:1, where 0.0002 is ILC, 0.0141 is CLC, the service type is W, A:5 is a V2H channel, and NA specifies that there is no I2H channel.
-
Queries or sets status information for an interval.
Table 1274 Queries Term
Definition
Set
Takes an optional list of status conditions (or negated status conditions) and applies those status conditions and the given expression to form an interval value
Status
Returns 1.0 if the interval has the specified statuses. These can be combined in AND or OR fashion.
-
These functions may only appear at the very top level of a formula. They return scalar values and will set the isScalar field of the IntervalData object to true. The peak and low functions will return the 'n' highest (or lowest) values found. Coincidence peak and low functions take exactly two arguments. 'aggregate' represents the aggregated interval stream. The interval from the 'contributor' channel at the time of the peak or low will be returned.
Table 1275 Functions Term
Definition
Scalar Average
Computes the average across the stream of data
Scalar Coincident Lows
Finds the first low in 'aggregate' and returns the coincident value from 'contributor'. Must give exactly 2 expressions
Scalar Coincident Peaks
Finds the first peak in 'aggregate' and returns the coincident value from 'contributor'. Must give exactly 2 expressions
Scalar Low
Returns the 'n' lowest value in the interval stream
Scalar Peak
Returns the 'n' highest value in the interval stream
Scalar Sum
Computes the sum across the stream of data
Within the Operators folder are the sub-categories:
-
Table 1276 Arithmetic Term
Definition
-
Subtraction
--
Decrement
()
Parentheses
*
Multiplication
/
Division
^
Exponentiation
|
Bitwise OR
+
Addition
++
Increment
-
Table 1277 Comparison Term
Definition
!=
Not Equal
<
Less than
<=
Less than or equal
=
Equal
>
Greater than
>=
Greater than or equal
-
Table 1278 Logical Term
Definition
AND
Logical AND
NOT
Logical NOT
OR
Logical OR
-
- Select a token and click Add, or double-click a token directly to add it to the formula work space.
- Click Search to open the standard IEE search dialog to search for entities to add to the formula.
- Click OK when the formula (or the part you are creating using the Expression Builder) is configured.
The Expression Builder dialog closes and the formula segment you built displays on the white board at the cursor.
If there is a logical inconsistency in the formula, a warning message appears. Make the appropriate corrections and click OK.
- Click Validate to check formula logic and verify the complete formula works.
If the configuration works, a confirmation message appears. If there is a logical incompatibility, an error message appears.
Caution: The Validate button validates formula logic. It does not validate interval data.
- Click OK. The formula is entered into the formula field.
ConversionWithin the Options folder is the sub-category:
|
Term |
Definition |
|---|---|
|
Daily Statistics |
Summarize statistics for each local time calendar day |
|
Monthly Statistics |
Summarize statistics for each local time calendar month |
|
Weekly Statistics |
Summarize statistics for each week. Week begins on Sunday at midnight, local time |
Within the Variables folder is the sub-category:
|
Term |
Definition |
|---|---|
|
Input |
Use passed-in data as service point |
|
Input: |
Use passed-in data as service point channel, specify as '$input:n' |
|
Iph |
Number of intervals per hour |
|
Num Intervals |
Total number of intervals |
|
Sp |
Output service point, specify as '$sp:n' |
|
Spc |
Output service point channel |
|
Usage Value |
Current interval value as usage |
Note: Advanced formula supports either variable $input or $input:XX, but not if both are used in the same formula.